The weston-launch protocol
~~~~~~~~~~~~~~~~~~~~~~~~~~
This protocol is used by vtmux and must be followed by any clients willing
to use DRI or input devices while running under vtmux.

The application is spawned with an open fd referring to the VT manager ctrl
channel. The fd is always 3 in vtmux, while in weston-launcher its value is
passed via WESTON_LAUNCHER_SOCK environment variable.

To run any clients relying on the variable with vtmux, make sure to do

	setenv WESTON_LAUNCHER_SOCK 3

in the startup script. To run any non-DRI clients with vtmux, make sure
to close fd 3 in the startup script. Any DRI clients should mark it CLOEXEC
as soon as possible. Passing fd 3 to children is a security risk.


Communication protocol
~~~~~~~~~~~~~~~~~~~~~~
The ctrl fd is a SOCK_SEQPACKET. The generic framing for both requests and
replies is this:

	struct pmsg {
		int code;
		char payload[];
	};

The format for payload[] depends on the code.

The client normally only sends requests to which the manager replies.
The manager may also send spontaneous notifications.

Negative code indicate error the usual way (-ENOENT etc).


Opening managed devices
~~~~~~~~~~~~~~~~~~~~~~~
Instead of attempting to open /dev/dri/card* or /dev/input/event* directly
via syscalls to the kernel, the client must request them from the manager
by sending the the following message:

	struct pmsg_open {
		int code = 0 (PIPE_CMD_OPEN)
		int mode = O_RDWR    <-- ignored
		char path[] = "/dev/dri/card0"
	}

The server replies with code=0 (PIPE_REP_OK) and passes fd in ancillary data.

Figuring out which devices to open is up to the client.

There is *NO* way to notify the manager that the fd is not needed atm.
The client should probably just close its copy of the fd.

A successful attempt to open /dev/dri/cardN yields a mastering fd.


VT switches
~~~~~~~~~~~
Whenever client's VT becomes a background one, the manager yanks DRI master
from the DRI fds, disables input fds, and sends

	struct pmsg {
		int code = 2 (PIPE_REP_DEACTIVATE)
	}

to the client. The client *may* notice the lack of DRI mastering before the
notification arrives, and must be ready to handle the situation. Upon receiving
this notification, the client should close all input fds.

When the VT becomes foreground again, the manager sends

	struct pmsg {
		int code = 1 (PIPE_REP_ACTIVATE)
	}

to the client. This notification means DRI mastering has been restored,
and the client should try re-opening all input devices it needs.


Adapting logind integration code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most projects that need managed device access in Linux come with logind
integration nowadays. Logind code does effectively the same thing and if
it's there already, adding weston-launch support should not require major
changes to the application. However, the meaning of messages being transmitted
differ between the two, which may cause some confusion.

When VT switch happens, WL sends a single message (ACTIVATE or DEACTIVATE)
to notify the application that the switch happened and *all* its devices have
been enabled or disabled. Logind sends one message per device, indicating that
one particular device has been enabled or disabled. Some applications (Xorg)
do not bother with partial resumes and wait until messages for all devices
arrive to resume normal operations. The code that does this is not needed for
weston-launch protocol.

When resuming a VT, logind re-opens input devices and sends new file
descriptors to the application. Weston-launch does not re-open any devices
itself, it's up to the application to send relevant OPEN commands after getting
ACTIVATE notification. For most applications, closing all inputs on DEACTIVATE
and tring to open all available nodes on ACTIVATE is the right thing to do.
There are no guarantees that the nodes will remain the same across VT switch.


Implementation notes
~~~~~~~~~~~~~~~~~~~~
DEACTIVATE message always arrives late, after the devices have been disabled.
The application should be ready to get unexpected EPERM when doing mastering
ioctls on DRI devices, marking the device as inactive when this happens.
The device should only be re-activated when ACTIVATE arrives.

Disabled inputs just stop sending events. On DEACTIVATE, all inputs should
be closed. On ACTIVATE, the application should scan and open available input
nodes.

DEACTIVATE and ACTIVATE notification *may* arrive in-between OPEN request
and OPEN reply. The application should be able to copy with this. At the very
least, upon getting cmd > 0 in reply to OPEN, it should repeat recv().

Handling interrupted switch properly is tricky, and not necessary in most
cases. VT switching is usually initiated by the user, who should be able
to retry after a mis-switch. Check src/vtmux/stubvt.c for example.
